---
id: oauth2
title: OAuth 2.0
---

This section describes on a high level what OAuth 2.0 is and how it works.
Please keep in mind that ORY Hydra is a technology targeted at professionals
using OAuth 2.0 on a regular basis. While we try to cover some of the concepts,
OAuth 2.0 and OpenID knowledge is expected from you in order to understand and
use ORY Hydra to its fullest potential.

If you are new to these topics we recommend watching the following talk

<iframe
  width="560"
  height="315"
  src="https://www.youtube.com/embed/996OiexHze0"
  frameborder="0"
  allowfullscreen
></iframe>

and read these articles:

- [DigitalOcean: An Introduction to OAuth 2](https://www.digitalocean.com/community/tutorials/an-introduction-to-oauth-2)
- [Aaron Parecki: OAuth2 Simplified](https://aaronparecki.com/2012/07/29/2/oauth2-simplified)
- [Zapier: Chapter 5: Authentication, Part 2](https://zapier.com/learn/apis/chapter-5-authentication-part-2/)

:::note

If you are not building a system that involves third parties - for example a
third party company (CircleCI) using your (GitHub) APIs - but instead are
looking to solve "Single Sign On", mobile / single page app authentication, or
generally "I want an API token after someone logs in", take a look at
[ORY Kratos](https://www.ory.sh/kratos) instead!

:::

### OAuth 2.0

[The OAuth 2.0 authorization framework](https://tools.ietf.org/html/rfc6749) is
specified in [IETF RFC 6749](https://tools.ietf.org/html/rfc6749). OAuth 2.0
enables a third-party application to obtain limited access to resources on an
HTTP server on behalf of the owner of those resources.

Why is this important? Without OAuth 2.0, a resource owner who wants to share
resources in their account with a third party would have to share their
credentials with that third party. As an example, let's say you (a resource
owner) have some photos (resources) stored on a social network (the resource
server). Now you want to print them using a third-party printing service. Before
OAuth 2.0 existed, you would have to enter your social network password into the
printing service so that it can access and print your photos. Sharing secret
passwords with third parties is obviously very problematic.

OAuth addresses this problem by introducing:

- the distinction between resource ownership and resource access for clients
- the ability to define fine-grained access privileges (called OAuth scopes)
  instead of full account access for third parties
- an authorization layer and workflow that allows resource owners to grant
  particular clients particular types of access to particular resources.

With OAuth, clients can request access to resources on a server, and the owner
of these resources can grant the requested access together with dedicated
credentials. In our example, you could grant the printing service read-only
access to your photos (only your photos, not your friend list) on the social
network. These credentials come in the form of an access token -- a string
denoting a specific scope, lifetime, and other access attributes. The client
(printing service) can use this access token to request the protected resources
(your photos) from the resource server (the social network).

### Terminology

To read more natural, this guide uses simpler terminologies like _user_ instead
of _resource owner_. Here is a full list of terms.

1. A **resource owner** is the user account who authorizes an external
   application to access their account. This access is limited (scoped) to
   particular actions (the granted "scopes" like read photos or write messages).
   This guide refers to resource owners as _users_ or _end users_.
2. The **OAuth 2.0 Authorization Server** implements the OAuth 2.0 protocol (and
   optionally OpenID Connect). In our case, this is **ORY Hydra**.
3. The **resource provider** is the service that hosts (provides) the resources.
   These resources (e.g. blog articles, printers, todo lists) are owned by a
   resource owner (user) mentioned above.
4. The **OAuth 2.0 Client** is the _external application_ that wants to access a
   resource owner's resources (read a user's images). To do that, it asks the
   OAuth 2.0 Authorization Server for an access token in a resource owner's
   behalf. The authorization server will ask the user if he/she "is ok with"
   giving that external application e.g. write access to personal images.
5. The **Identity Provider** is a service that allows users to register
   accounts, log in, etc.
6. **User Agent** is usually a browser.
7. **OpenID Connect** is a protocol built on top of OAuth 2.0 for just
   authentication (instead of authorizing access to resources).

A typical OAuth 2.0 flow looks as follows:

1. A developer registers an OAuth 2.0 Client (external application) with the
   Authorization Server (ORY Hydra) the intention to obtain information on
   behalf of a user.
2. The application UI asks the user to authorize the application to access
   information/data on his/her behalf.
3. The user is redirected to the Authorization Server.
4. The Authorization Server confirms the user's identity and asks the user to
   grant the OAuth 2.0 Client certain permissions.
5. The Authorization Server issues tokens that the OAuth 2.0 client uses to
   access resources on the user's behalf.

### OAuth 2.0 Scope

:::note

Please read the section about OAuth2 Scope in
[Read this before learning OAuth2 / OpenID Connect](./before-oauth2.mdx).

A second important concept is the OAuth 2.0 Scope. Many people confuse OAuth 2.0
Scope with internal Access Control like for example Role Based Access Control
(RBAC) or Access Control Lists (ACL). Both concepts cover different aspects of
access control.

Internal access control (RBAC, ACL, etc) decides what a user can do in your
system. An administrator might be allowed to modify everything. A regular user
might only be allowed to read their own messages.

OAuth 2.0 Scopes, on the other hand, describe what a user allowed an external
application (OAuth 2.0 client) to do on his/her behalf. For example, an access
token might grant the external application to see a user's pictures, but not
upload new pictures on his/her behalf (which we assume a user could do herself).

In an extreme case, the user could lie and grant an external application OAuth
scopes that he himself doesn't have permission to ("read all classified
documents"). The OAuth Access Token with those scopes wouldn't help the external
application read those documents because it can only act in the name of the
user, and that user doesn't have these access privileges.

The scope of an OAuth 2.0 scope defines the permission the token was granted by
the end-user. For example, a specific token might be allowed to access public
pictures, but not private ones. The granted permissions are established during
the consent screen.

ORY Hydra has pre-defined OAuth 2.0 Scope values:

- `offline_access`: Include this scope if you wish to receive a refresh token
- `openid`: Include this scope if you wish to perform an OpenID Connect request.

When performing an OAuth 2.0 Flow where the end-user is involved (e.g. Implicit
or Authorize Code), the granted OAuth 2.0 Scope must be set when accepting the
consent using the `grant_scope` key.

### OAuth 2.0 Access Token Audience

The Audience of an Access Token refers to the Resource Servers that this token
is intended for. The audience usually refers to one or more URLs such as

- `https://api.mydomain.com/blog/posts`
- `https://api.mydomain.com/users`

but may also refer to a subset of resources:

- `https://api.mydomain.com/tenants/foo/users`

When performing an OAuth 2.0 Flow where the end-user is involved (e.g. Implicit
or Authorize Code), the granted audience must be set when accepting the consent
using the `grant_access_token_audience` key. In most cases, it is ok to grant
the audience without user-interaction.

### OAuth 2.0 Refresh Tokens

OAuth 2.0 Refresh Tokens are issued only when an Authorize Code Flow
(`response_type=code`) or an OpenID Connect Hybrid Flow with an Authorize Code
Response Type (`response_type=code+...`) is executed. OAuth 2.0 Refresh Tokens
are not returned for Implicit or Client Credentials grants:

Capable of issuing an OAuth 2.0 Refresh Token:

- https://ory-hydra.example/oauth2/auth?response_type=code&...
- https://ory-hydra.example/oauth2/auth?response_type=code+token&...
- https://ory-hydra.example/oauth2/auth?response_type=code+token+id_token&...
- https://ory-hydra.example/oauth2/auth?response_type=code+id_token&...

Will not issue an OAuth 2.0 Refresh Token:

- https://ory-hydra.example/oauth2/auth?response_type=token&...
- https://ory-hydra.example/oauth2/auth?response_type=token+id_token&...
- https://ory-hydra.example/oauth2/token?grant_type=client_redentials&...

Additionally, each OAuth 2.0 Client that wants to request an OAuth 2.0 Refresh
Token must be allowed to request scope `offline_access`. When performing an
OAuth 2.0 Authorize Code Flow, the `offline_access` value must be included in
the requested OAuth 2.0 Scope:

```
https://authorization-server.com/auth
 &scope=offline_access
 ?response_type=code
 &client_id=...
 &redirect_uri=...
 &state=...
```

When [accepting the consent request](consent), `offline_access` must be in the
list of `grant_scope`:

```js
fetch('https://hydra/oauth2/auth/requests/consent/accept?challenge=' + encodeURIComponent(challenge), {
    method: 'PUT',
    body: JSON.stringify(body),
    headers: { 'Content-Type': 'application/json' }
}).
const body = {
    grant_scope: ["offline_access"],
}
```

Refresh Token Lifespan can be set using configuration key `ttl.refresh_token`.
If set to -1, Refresh Tokens never expire.

### OAuth 2.0 Token Introspection

OAuth2 Token Introspection is an [IETF](https://tools.ietf.org/html/rfc7662)
standard. It defines a method for a protected resource to query an OAuth 2.0
authorization server to determine the active state of an OAuth 2.0 token and to
determine meta-information about this token. OAuth 2.0 deployments can use this
method to convey information about the authorization context of the token from
the authorization server to the protected resource.

The usage of an access token or client credentials is required to access the
endpoint. ORY Hydra will however accept any valid token or valid credentials as
there is no built-in access control.
